HAL SAI migration: List of applicable concepts

This section provides information about the HAL SAI applicable architecture concepts.

Concepts for SAI

Concept	Description
Separation of initialization and configuration functions	Initialization has been split into separate initialization and configuration functions: HAL_SAI_Init(): initializes the SAI according to the specified parameters. HAL_SAI_SetConfig(): sets the configuration of the SAI peripheral.
Removal and conversion of init structure to configuration structure	The initialization structure SAI_InitTypeDef has been removed from the handle and moved into the hal_sai_config_t configuration structure.
Renaming of the handle structure	The handle structure has been renamed to hal_sai_handle_t.
Renaming unitary init structures	The SAI_InitTypeDef structure has been replaced by hal_sai_config_t.
Remove MspInit and MspDeInit callbacks	The functions hal_sai_MspInit() and hal_sai_MspDeInit() have been removed and replaced by a user-defined sequence for SAI initialization and configuration.
Unitary configuration APIs	New APIs have been introduced to get and set SAI features.
Dedicated DMA link APIs replace generic __HAL_LINKDMA macro	In HAL2, DMA link APIs are provided with explicit naming and parameters : HAL_SAI_SetTxDMA() and HAL_SAI_SetRxDMA().
Individual callback registration APIs replace global register and unregister functions	Split global register callback SAI into one register per callback and remove unregister callback SAI.
Removal of hardware-related macros in HAL2	All hardware macros have been removed from the HAL SAI driver, and equivalent services are converted into HAL static inline APIs.
Revised and optimized HAL state machine	The SAI state machine has been reworked to ensure transitions between the peripheral’s functional states.
Revised and optimized HAL API status returns	The HAL SAI functions were updated to return: HAL_INVALID_PARAM: in case of a NULL p_config structure pointer. HAL_ERROR: in case of an error. HAL_TIMEOUT: in case of a user timeout. HAL_BUSY: in case of an ongoing process. HAL_OK: in case of a successfully completed operation
Revised and optimized HAL error management	Rename the error management function to HAL_SAI_GetLastErrorCodes().
Replaced TypeDef suffix with _t in type names	All TypeDef parts of the HAL SAI driver have been removed and replaced by _t.
Assertion implementation and usage in HAL1	The ASSERT_DBG_STATE and ASSERT_DBG_PARAM macros are used to check the parameters and state of the HAL SAI driver.
Merge HAL extension files with common ones and remove the EX prefix from APIs.	Only one HAL SAI header file remains and all macros, define statements, and functions from hal_sai_ex.h have been adapted and merged into hal_sai.h.
Provide RTOS-compatible acquire/release bus services for communication peripheral drivers.	New functions, HAL_SAI_AcquireBus() and HAL_SAI_ReleaseBus(), are provided to allow the acquisition and release of a HAL SAI handle, protecting a full sequence.
Add HAL PPP Services for Drivers with Handle to Retrieve Corresponding Peripheral Clock Frequency.	The HAL SAI driver provides a new API to retrieve the clock frequency: HAL_SAI_GetClockFreq().
Replace Finite Parameter Defines (Including PPP Instances) with Enum Types at HAL Levels.	Finite parameters (including SAI instances) have been converted into enumerated types (enums) at HAL level. This improves code readability, maintainability, and type safety.
Add HAL_PPP Prefix to All HAL Peripheral APIs (Defines, Macros, Types, and Functions).	All HAL SAI functions start with HAL_SAI. All HAL SAI enumerations and structures start with hal_sai.

Other HAL SAI changes

Concept	Consideration
Remove HAL_SAI_InitProtocol()	The function HAL_SAI_InitProtocol() has been removed in HAL2. The functionality has been consolidated into the HAL_SAI_SetConfig() function.